<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>getmsg</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_608">&nbsp;</a>NAME</h4><blockquote>
getmsg, getpmsg - receive next message from a STREAMS file
</blockquote><h4><a name = "tag_000_005_609">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="stropts.h.html">stropts.h</a>&gt;

int getmsg(int <i>fildes</i>, struct strbuf *<i>ctlptr</i>, struct strbuf *<i>dataptr</i>,
    int *<i>flagsp</i>);
int getpmsg(int <i>fildes</i>, struct strbuf *<i>ctlptr</i>, struct strbuf *<i>dataptr</i>,
    int *<i>bandp</i>, int *<i>flagsp</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_610">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>getmsg()</i>
function retrieves the contents of a message located at the head of the STREAM
head read queue associated with a STREAMS file and places the contents into
one or more buffers.  The message contains either a data part, a control
part, or both.  The data and control parts of the message are placed into
separate buffers, as described below.  The semantics of each part is defined
by the originator of the message.
<p>
The
<i><a href="getpmsg.html">getpmsg()</a></i>
function does the same thing as
<i>getmsg()</i>,
but provides finer control over the priority of the messages received.
Except where noted, all requirements on
<i>getmsg()</i>
also pertain to
<i><a href="getpmsg.html">getpmsg()</a></i>.
<p>
The <i>fildes</i> argument specifies a file descriptor referencing a
STREAMS-based file.
<p>
The <i>ctlptr</i> and <i>dataptr</i> arguments each point to a <b>strbuf</b>
structure, in which the <b>buf</b> member points to a buffer in which the data
or control information is to be placed, and the <b>maxlen</b> member indicates
the maximum number of bytes this buffer can hold.  On return, the <b>len</b>
member contains the number of bytes of data or control information actually
received.  The <b>len</b> member is set to 0 if there is a zero-length control
or data part and <b>len</b> is set to -1 if no data or control information
is present in the message.
<p>
When
<i>getmsg()</i>
is called, <i>flagsp</i> should point to an integer that indicates the type of
message the process is able to receive.  This is described further below.
<p>
The <i>ctlptr</i> argument is used to hold the control part of the message, and
<i>dataptr</i> is used to hold the data part of the message.  If <i>ctlptr</i>
(or <i>dataptr</i>) is a null pointer or the <b>maxlen</b> member is -1, the
control (or data) part of the message is not processed and is left on the
STREAM head read queue, and if the <i>ctlptr</i> (or <i>dataptr</i>) is not a
null pointer, <b>len</b> is set to -1.  If the <b>maxlen</b> member is set to
0 and there is a zero-length control (or data) part, that zero-length part is
removed from the read queue and <b>len</b> is set to 0.  If the <b>maxlen</b>
member is set to 0 and there are more than 0 bytes of control (or data)
information, that information is left on the read queue and <b>len</b> is set
to 0.  If the <b>maxlen</b> member in <i>ctlptr</i> (or <i>dataptr</i>) is less
than the control (or data) part of the message, <b>maxlen</b> bytes are
retrieved.  In this case, the remainder of the message is left on the STREAM
head read queue and a non-zero return value is provided.
<p>
By default,
<i>getmsg()</i>
processes the first available message on the STREAM head read queue.  However,
a process may choose to retrieve only high-priority messages by setting the
integer pointed to by <i>flagsp</i> to RS_HIPRI.  In this case,
<i>getmsg()</i>
will only process the next message if it is a high-priority message.  When
the integer pointed to by <i>flagsp</i> is 0, any message will be retrieved.
In this case, on return, the integer pointed to by <i>flagsp</i> will be set to
RS_HIPRI if a high-priority message was retrieved, or 0 otherwise.
<p>
For
<i><a href="getpmsg.html">getpmsg()</a></i>,
the flags are different.
The <i>flagsp</i> argument points to a bitmask with the following
mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND and MSG_ANY.
Like
<i>getmsg()</i>,
<i><a href="getpmsg.html">getpmsg()</a></i>
processes the first available message on the STREAM head read queue.  A
process may choose to retrieve only high-priority messages by setting the
integer pointed to by <i>flagsp</i> to MSG_HIPRI and the integer pointed to by
<i>bandp</i> to 0.  In this case,
<i><a href="getpmsg.html">getpmsg()</a></i>
will only process the next message if it is a high-priority message.  In a
similar manner, a process may choose to retrieve a message from a particular
priority band by setting the integer pointed to by <i>flagsp</i> to MSG_BAND
and the integer pointed to by <i>bandp</i> to the priority band of interest.
In this case,
<i><a href="getpmsg.html">getpmsg()</a></i>
will only process the next message if it is in
a priority band equal to, or greater than, the integer pointed to
by <i>bandp</i>, or if it is a high-priority message.
If a process just wants to get the first message off the queue,
the integer pointed to by <i>flagsp</i> should be set to MSG_ANY
and the integer pointed to by <i>bandp</i> should be set to 0.
On return, if the message retrieved was a high-priority message,
the integer pointed to by <i>flagsp</i> will
be set to MSG_HIPRI and the integer pointed to by <i>bandp</i> will be set to
0.  Otherwise, the integer pointed to by <i>flagsp</i> will be set to MSG_BAND
and the integer pointed to by <i>bandp</i> will be set to the priority band of
the message.
<p>
If O_NONBLOCK is not set,
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
will block until a message of the type specified by <i>flagsp</i> is available
at the front of the STREAM head read queue.  If O_NONBLOCK is set and a
message of the specified type is not present at the front of the read queue,
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
fail and set <i>errno</i> to [EAGAIN].
<p>
If a hangup occurs on the STREAM from which messages are to be retrieved,
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
continue to operate normally, as described above, until the STREAM head read
queue is empty.  Thereafter, they return 0 in the <i>len</i> members of
<i>ctlptr</i> and <i>dataptr</i>.
</blockquote><h4><a name = "tag_000_005_611">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
return a non-negative value.  A value of 0 indicates that a full message was
read successfully.  A return value of MORECTL indicates that more control
information is waiting for retrieval.  A return value of MOREDATA indicates
that more data is waiting for retrieval.  A return value of the bitwise
logical OR of MORECTL and MOREDATA indicates that both types of information
remain.  Subsequent
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
calls retrieve the remainder of the message.  However, if a message of higher
priority has come in on the STREAM head read queue, the next call to
<i>getmsg()</i>
or
<i><a href="getpmsg.html">getpmsg()</a></i>
retrieves that higher-priority message before retrieving the remainder of the
previous message.
<p>
If the high priority control part of the message is consumed, the
message will be placed back on the queue as a normal message of band 0.
Subsequent
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
calls retrieve the remainder of the message.
If, however, a priority message arrives or already exists on the
STREAM head, the subsequent call to
<i>getmsg()</i>
or
<i><a href="getpmsg.html">getpmsg()</a></i>
retrieves the higher-priority message before retrieving the remainder
of the message that was put back.
<p>
Upon failure,
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
return -1 and set <i>errno</i> to indicate the error.
</blockquote><h4><a name = "tag_000_005_612">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
functions will fail if:
<dl compact>

<dt>[EAGAIN]<dd>
The O_NONBLOCK flag is set and no messages are available.

<dt>[EBADF]<dd>
The <i>fildes</i> argument is not a valid file descriptor open for reading.

<dt>[EBADMSG]<dd>
The queued message to be read is not valid for
<i>getmsg()</i>
or
<i><a href="getpmsg.html">getpmsg()</a></i>
or a pending file descriptor is at the STREAM head.

<dt>[EINTR]<dd>
A signal was caught during
<i>getmsg()</i>
or
<i><a href="getpmsg.html">getpmsg()</a></i>.

<dt>[EINVAL]<dd>
An illegal value was specified by <i>flagsp</i>, or the STREAM or multiplexer
referenced by <i>fildes</i> is linked (directly or indirectly) downstream from
a multiplexer.

<dt>[ENOSTR]<dd>
A STREAM is not associated with <i>fildes</i>.

</dl>
<p>
In addition,
<i>getmsg()</i>
and
<i><a href="getpmsg.html">getpmsg()</a></i>
will fail if the STREAM head had processed an asynchronous error before the
call.  In this case, the value of
<i>errno</i>
does not reflect the result of
<i>getmsg()</i>
or
<i><a href="getpmsg.html">getpmsg()</a></i>
but reflects the prior error.
</blockquote><h4><a name = "tag_000_005_613">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_614">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_615">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_616">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="poll.html">poll()</a></i>,
<i><a href="putmsg.html">putmsg()</a></i>,
<i><a href="read.html">read()</a></i>,
<i><a href="write.html">write()</a></i>,
<i><a href="stropts.h.html">&lt;stropts.h&gt;</a></i>,
<a href="STREAMS.html">STREAMS overview</a>.
<br>
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
